---
title: engine
description: The engine configuration reference
---

The `engine` configuration allows you to specify which tool should be used for executing plan and apply operations. Terrateam supports multiple tools, including Terraform, OpenTofu, Terragrunt, Pulumi, CDKTF, and custom engines. This configuration can be defined globally or overridden per workflow by including it under the `workflows` key.

## Default Configuration
```yaml
engine:
  name: terraform
  tf_version: latest
```

## Keys

There are different valid keys depending on the engine `name`.

| Key | Type | Description |
|-----|------|-------------|
| name | String | The name of the tool to use for executing Terraform operations. Can be `terraform`, `tofu`, `terragrunt`, `cdktf`, or `custom`. Default is `terraform`. |

### terraform and tofu

| Key | Type | Description |
|-----|------|-------------|
| name | String | `terraform` or `tofu` depending on which specific implementation to use. |
| override_tf_cmd | String | By default, either `terraform` or `tofu` is used to run operations.  This configuration overrides the program to call. |
| version | String | Which version of the `terraform` or `tofu` to use. |
| outputs | Object | See `outputs` below. |

### terragrunt

| Key | Type | Description |
|-----|------|-------------|
| name | String | `terragrunt` |
| override_tf_cmd | String | Override the name of the Terragrunt program to run. |
| tf_cmd | String | Which underlying Terraform-compatible program to use.  By default it is `terraform`. |
| tf_version | String | The version of the underlying Terraform-compatible tool to use (either Terraform or Tofu). |
| version | String | The version of Terragrunt to use. |
| outputs | Object | See `outputs` below. |

### cdktf

| Key | Type | Description |
|-----|------|-------------|
| name | String | `cdktf` |
| override_tf_cmd | String | Override the name of the CDKTF program to run. |
| tf_cmd | String | Which underlying Terraform-compatible program to use.  By default it is `terraform`. |
| tf_version | String | The version of the underlying Terraform-compatible tool to use (either Terraform or Tofu). |
| outputs | Object | See `outputs` below. |

## custom

All custom engine steps are optionally and will simply be skipped if they are not specified.

| Key | Type | Description |
|-----|------|-------------|
| init | Array | The command to run during the init step. |
| plan | Array | The command to run during the plan step. The `TERRATEAM_PLAN_FILE` environment variable is available to write a plan file that will be accessible in the apply step.  This plan file is up to the engine to define and use as it needs. |
| diff | Array | The command to produce a human-readable diff of the plan output. |
| apply | Array | The command to run during the apply step. |
| outputs | Array | The command to return output values as a JSON string. |

## outputs

By default, Terrateam collects the outputs of all apply runs an stores them.  The `outputs` configuration controls this behaviour.

| Key | Type | Description |
|-----|------|-------------|
| collect | Boolean | `true` to collect outputs, `false` to disable.  Default is `true`.

## Examples
### Using Terraform
```yaml
engine:
  name: terraform
  version: '1.0.0'
```

### Using OpenTofu
```yaml
engine:
  name: tofu
  version: '1.9.0'
```

### Using Terragrunt with a Specific Terraform Version
```yaml
engine:
  name: terragrunt
  tf_version: '1.11.1'
```

### Using Terragrunt with OpenTofu
```yaml
engine:
  name: terragrunt
  tf_cmd: tofu
```

### Using CDKTF with the Latest Terraform Version
```yaml
engine:
  name: cdktf
```

### Using Pulumi
```yaml
engine:
  name: pulumi
```

### Using a Custom Engine
```yaml
engine:
  name: custom
  init: ['echo', 'init']
  plan: ['my-custom-plan']
  diff: ['printf', '+ added foo\n- removed bar\n~ updated baz\n']
  apply: ['my-custom-apply']
  outputs: ['echo', '{"foo": "bar"}']
```
This configuration defines a fully custom engine using shell commands for each step. All steps are optional - you can define only what you need.

## Considerations
When configuring `engine`, keep the following in mind:
- The `terraform` engine is the default and most commonly used option. It directly uses the Terraform CLI for executing Terraform operations.
- The `tofu` engine uses OpenTofu, an open-source reimplementation of the Terraform CLI. It provides additional features and enhancements over the standard Terraform CLI.
- The `terragrunt` engine uses Terragrunt, a thin wrapper for Terraform that provides extra tools for keeping your configurations DRY, working with multiple Terraform modules, and managing remote state.
- The `cdktf` engine uses CDKTF (Cloud Development Kit for Terraform), which allows you to define your infrastructure using familiar programming languages like TypeScript, Python, Go, and Java.
- When using `terragrunt` or `cdktf`, you can specify the version of Terraform or OpenTofu CLI to use with the `tf_version` option. This allows you to control the underlying Terraform version independently of the Terragrunt or CDKTF version.
- The `custom` engine allows full control over each step in the pipeline. All steps are optional - you may specify only the steps relevant to your use case. The `TERRATEAM_PLAN_FILE` environment variable allows passing data from the plan step to the apply step. The `outputs` step, if defined, must return valid JSON.
